home *** CD-ROM | disk | FTP | other *** search
/ Gamers Delight 2 / Gamers Delight 2.iso / Aminet / game / role / pinfocom_3_0.lha / Docs / pinfo_ti.txt < prev    next >
Text File  |  1992-10-22  |  32KB  |  859 lines
  1.  
  2.  
  3.  
  4. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  5.  
  6.  
  7. NAME
  8.        pinfo_ti  -  Description  of  the terminal interface to the portable
  9.        Infocom datafile interpreter.
  10.  
  11. SYNOPSIS
  12.        #include <stdio.h>
  13.        #include "infocom.h"
  14.  
  15.        extern gflags_t gflags;
  16.        extern char     *ti_location;
  17.        extern char     *ti_status;
  18.  
  19.  
  20.        const char *scr_usage;
  21.        const char *scr_long_usage;
  22.        const char *scr_opt_list;
  23.  
  24.        int scr_cmdarg( int argc, char ***argv_p );
  25.  
  26.        int scr_getopt( int c, const char *arg );
  27.  
  28.        void scr_setup( int margin,
  29.                        int indent,
  30.                        int lines,
  31.                        int context );
  32.  
  33.        void scr_begin();
  34.  
  35.        void scr_putline( const char *buffer );
  36.  
  37.        void scr_putscore();
  38.  
  39.        void scr_putsound( int number,
  40.                           int action,
  41.                           int volume,
  42.                           int argc );
  43.  
  44.        void scr_putmesg( const char *buffer, Bool is_error );
  45.  
  46.        int scr_getline( const char *prompt,
  47.                         int length,
  48.                         char *buffer );
  49.  
  50.        void scr_window( int size );
  51.  
  52.        void scr_set_win( int win );
  53.  
  54.        FILE *scr_open_sf( int length, char *buffer, int type );
  55.  
  56.        void scr_close_sf( const char *buffer, FILE *fp, int is_save );
  57.  
  58.        void scr_end();
  59.  
  60.        void scr_shutdown();
  61.  
  62.  
  63.  
  64. Revision 3.0                    21 October 1992                               1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  71.  
  72.  
  73. DESCRIPTION
  74.        These routines form  the  interface  between  the  portable  Infocom
  75.        datafile  interpreter  (pinfocom) and a particular type of terminal.
  76.        The pinfocom package comes with interfaces to the following terminal
  77.        types:
  78.  
  79.        termcap
  80.               This terminal type supports all(?) UNIX systems via an inter-
  81.               face to either termcap or terminfo  terminal  capability  and
  82.               either  termio,  termios,  or  sgtty line discipline control.
  83.               Optional support for the GNU readline line editing  and  his-
  84.               tory library is also available.
  85.  
  86.        amiga  This  terminal  type  supports  an Amiga interface, including
  87.               sound  and  command  line  editing.   See  amiga.c  for  full
  88.               details.
  89.  
  90.        msdos  This  terminal  type  supports  MS-DOS  based  systems.   See
  91.               msdos.c for full details.
  92.  
  93.        stream This terminal type should support any system with  a  C  com-
  94.               piler;  it  uses simple C stdio routines that all C libraries
  95.               will have.  Nothing fancy, but it works.
  96.  
  97.        Also in the works is an X11-based interface.
  98.  
  99.        This man page describes the interface between the pinfo  interpreter
  100.        and  the  terminal  support  packages so that programmers can create
  101.        their own interfaces to new systems.   Terminal  interface  will  be
  102.        abbreviated to TI below.
  103.  
  104.    Environment
  105.        The  interpreter  operates in two modes: game-playing mode (default)
  106.        and information mode (if any of the command-line options -h, -o, -O,
  107.        -v  and/or  -V are given), where the game is not played but informa-
  108.        tion about it is instead displayed on the screen.
  109.  
  110.        All input and output in game-playing mode is done  via  the  scr_*()
  111.        functions  described  below.   Output during information mode is via
  112.        simple C stdio library functions.
  113.  
  114.        The only interface between the interpreter and the terminal handling
  115.        code  is through the functions and global variables described below;
  116.        no other symbols in the TI code should be externally visible and any
  117.        other  external  symbols  in  the  interpreter  code  are subject to
  118.        change.
  119.  
  120. GENERAL
  121.        Some general issues to be considered:
  122.  
  123.    Asynchronous Events
  124.        The interpreter registers a signal handler for the SIGINT signal and
  125.        sets to ignore the SIGQUIT signal (if defined).
  126.  
  127.  
  128.  
  129.  
  130. Revision 3.0                    21 October 1992                               2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  137.  
  138.  
  139.        Any  other  signals or other asynchronous events are free to be han-
  140.        dled by the TI as it sees fit.  Note, however, that  none  of  these
  141.        handler  routines  may  modify  or access any interpreter variables:
  142.        interpreter variables listed below are only guaranteed to  be  valid
  143.        when  one  of  the  scr_*() functions below has been properly called
  144.        from within the interpreter code.
  145.  
  146.    Proportional Fonts
  147.        If the TI supports multiple fonts it is perfectly reasonable to  use
  148.        proportional-width fonts for printing general game text if you wish.
  149.  
  150.        However, at  certain  points  in  the  game  fixed-width  fonts  are
  151.        required,  such  as  when  printing  maps, etc.  To accomodate this,
  152.        before printing to  the  screen  scr_putline()  (see  below)  should
  153.        invoke  the  macro  F2_IS_SET(B_FIXED_FONT).   If this macro returns
  154.        non-0 then the current buffer should be  printed  in  a  fixed-width
  155.        font;  if it returns 0 then a proportional-width font may be used if
  156.        desired.
  157.  
  158.    Scripting
  159.        All Infocom games support the script command, which is  supposed  to
  160.        begin  a transcript of the user's adventure.  Normally this initial-
  161.        ized the printer and all subsequent text and commands  were  printed
  162.        to the printer as well as to the screen.
  163.  
  164.        The  TI  may support this feature as well.  There's no Z-Code primi-
  165.        tive for turning on and off scripting, however: instead  a  flag  is
  166.        set  or  reset.   In  scr_putline() and scr_getline() the macro call
  167.        F2_IS_SET(B_SCRIPTING) should be used; if it returns non-0 then  the
  168.        output  line  or  prompt and command should be printed to the script
  169.        file as well as the display.
  170.  
  171.        The interface will call scr_open_sf() with a file type of  SF_SCRIPT
  172.        when  a script file is to be opened and scr_close_sf() when a script
  173.        file is to be closed.
  174.  
  175.    Fixed Window
  176.        Only Seastalker makes use of the fixed window  feature  in  Standard
  177.        Series games, but it's nice to have nevertheless.
  178.  
  179.        If  the  TI  can  support  a  fixed window in addition to the normal
  180.        scrolling text window then scr_begin() should notify the interpreter
  181.        by calling F1_SETB(B_STATUS_WIN).  In this case the scr_window() and
  182.        scr_set_win()  functions  described  below  will  be  used  to  cre-
  183.        ate/manage/delete the fixed window.
  184.  
  185.        If  the TI cannot support a fixed window then the above macro should
  186.        not be called and scr_window() and scr_set_win() may be dummy  func-
  187.        tions.
  188.  
  189. GLOBAL VARIABLES
  190.        These  global  variables are defined in the interpreter code and may
  191.        be used by the TI:
  192.  
  193.  
  194.  
  195.  
  196. Revision 3.0                    21 October 1992                               3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  203.  
  204.  
  205.    gflags
  206.        Contains global flags and other general variables of interest.   The
  207.        only  field  which may be modified is the pr_status field, if the TI
  208.        doesn't support status line printing.
  209.  
  210.    ti_location
  211.        This nul-terminated string is a short  description  of  the  current
  212.        location of the player, for printing on the status line.  It is usu-
  213.        ally displayed on the left-hand side of the status line.
  214.  
  215.    ti_status
  216.        This nul-terminated  string  contains  the  status  of  the  player.
  217.        Depending  on  the game this may be score, score and turn number, or
  218.        the current time in a 12-hour clock.  This string is usually printed
  219.        on the right-hand side of the status line.
  220.  
  221.        These  global  variables  should  be defined in the TI .c file; they
  222.        will be declared external where used in the interpreter code.
  223.  
  224.    scr_usage
  225.        The scr_usage variable should be initialized to a string  containing
  226.        info  about  any extra command-line options that the TI makes avail-
  227.        able.  Here's an example from the termcap TI:
  228.  
  229.            const char *scr_usage = "[-H file] [-C file]";
  230.  
  231.        If there are no extra command-line options the  variable  should  be
  232.        set to the empty string (""), not NULL.
  233.  
  234.    scr_long_usage
  235.        The  scr_long_usage  variable  should  be initialized to be a string
  236.        containing a one-line per option description of any  extra  command-
  237.        line  options  that  the TI makes available.  Here's an example from
  238.        the termcap TI:
  239.  
  240.            const char *scr_long_usage = "\
  241.            \t-H file\tread/store command history in file\n\
  242.            \t-C file\tread/store user command completions in file\n";
  243.  
  244.        If there are no extra command-line options the  variable  should  be
  245.        set to NULL.
  246.  
  247.    scr_opt_list
  248.        The  scr_opt_list variable should be initialized to be a string con-
  249.        taining  getopt(3)-style  descriptions  of  any  extra  command-line
  250.        options that the TI makes available.  Briefly, each option character
  251.        is placed in the string; if the option has an argument (no  optional
  252.        arguments allowed) then it should be immediately followed by a colon
  253.        (:).  Here's an example from the termcap TI:
  254.  
  255.            const char *scr_opt_list = "C:H:";
  256.  
  257.        If there are no extra command-line options the  variable  should  be
  258.        set to the nul string ("").
  259.  
  260.  
  261.  
  262. Revision 3.0                    21 October 1992                               4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  269.  
  270.  
  271. Interpreter Macros
  272.        The  following  macros are defined in infocom.h and available to the
  273.        TI writer for access to certain data structures.
  274.  
  275.        The flags available with F1_*() macros are:
  276.  
  277.        B_USE_TIME
  278.               If set them time is displayed on the status  line,  otherwise
  279.               score/moves  is  displayed.  This is a readonly value; the TI
  280.               cannot change it.
  281.  
  282.        B_TANDY
  283.               The Tandy license flag; if set then Tandy licensing  mode  is
  284.               turned on, otherwise it's turned off.
  285.  
  286.        B_ALT_PROMPT
  287.               The alternate prompt flag; if set then alternate prompting is
  288.               enabled, otherwise it's disabled.
  289.  
  290.        B_STATUS_WIN
  291.               If set the TI supports fixed windows (for Seastalker), if not
  292.               set it doesn't.
  293.  
  294.        The flags available with F2_*() macros are:
  295.  
  296.        B_SCRIPTING
  297.               If  set  then  scripting mode is currently enabled, otherwise
  298.               it's disabled.
  299.  
  300.        B_FIXED_FONT
  301.               If set then the current buffer must be printed  in  a  fixed-
  302.               width font if possible; otherwise it may be printed in a pro-
  303.               portional font.
  304.  
  305.        B_SOUND
  306.               If set the interpreter  may  issue  scr_putsound()  requests;
  307.               otherwise  it  won't.  Note this flag is readonly and may not
  308.               be set by the TI.
  309.  
  310.    F?_IS_SET()
  311.        This macro returns a 0 if the specified game header flag is not set,
  312.        and a non-0 (note not necessarily 1!)  if it is not set.
  313.  
  314.    F?_SETB()
  315.        This macro sets the specified game header flag.
  316.  
  317.    F?_RESETB()
  318.        This  macro  resets  (un-sets)  the specified game header flag.  The
  319.        following functions are defined in the interpreter and available  to
  320.        the  TI writer for use (no other functions in the interpreter should
  321.        be called).
  322.  
  323.    xmalloc()
  324.        This function calls malloc() and exits with an error if there is  no
  325.  
  326.  
  327.  
  328. Revision 3.0                    21 October 1992                               5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  335.  
  336.  
  337.        heap left.
  338.  
  339.    xrealloc()
  340.        This function calls realloc() and exits with an error if there is no
  341.        heap left.
  342.  
  343.    chop_buf()
  344.        buf    Buffer to be chopped.
  345.  
  346.        max    Max number of chars wanted
  347.  
  348.        This function locates the longest section of buf less than or  equal
  349.        to  max  characters  containing at least one complete word.  It does
  350.        not modify the buffer.  It returns a pointer to the space where  the
  351.        line should be broken, or to the nul character ('\0') if buf is less
  352.        than or equal to max chars long.
  353.  
  354.        This function is useful with fixed-width font TIs  for  chopping  up
  355.        the  buffer  passed  to scr_putline() into sections which fit on the
  356.        screen.  See examples of its use in stream.c.
  357.  
  358. TI Functions
  359.        The following functions need to be provided by the TI code.
  360.  
  361.    scr_cmdarg()
  362.        argc   Number of command-line args.
  363.  
  364.        argv_p Pointer to an array of strings; each one  is  a  command-line
  365.               argument.
  366.  
  367.        This  function will be called before any other scr_*() function, and
  368.        before the command-line arguments are examined by  the  interpreter.
  369.        It  allows the TI to add (and possibly remove) arguments to the com-
  370.        mand line.
  371.  
  372.        If the interface has the ability to determine  command-line  options
  373.        from  an alternate source, such as a configuration file, an environ-
  374.        ment variable, windowing resources, or saved game resources, then it
  375.        should  add  these  options to argv_p so they will be noticed by the
  376.        interpreter.
  377.  
  378.        Note that when  adding  options  they  should  be  inserted  between
  379.        (*argv_p)[0]  and  (*argv_p)[1], shifting the existing options over,
  380.        so that they will be properly overridden by any options given on the
  381.        command line.
  382.  
  383.        This  function  should return the number of elements in argv_p after
  384.        modification (the new argument count).  It is  expected  that  after
  385.        this function is called, (*argv_p)[0] remains the name of the inter-
  386.        preter program, (*argv_p)[1] to (*argv_p)[argc-1]  are  command-line
  387.        arguments, and (*argv_p)[argc] is 0 (NULL).
  388.  
  389.        Although  it  is  perfectly legal to remove arguments from argv_p as
  390.        well, this is trickier because you must follow  all  UNIX  getopt(1)
  391.  
  392.  
  393.  
  394. Revision 3.0                    21 October 1992                               6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  401.  
  402.  
  403.        conventions.   It  is suggested that scr_getopt() is used to process
  404.        arguments on the command line, and scr_cmdarg()  used  only  to  add
  405.        extra arguments if needed.
  406.  
  407.    scr_getopt()
  408.        c      The command-line option character.
  409.  
  410.        arg    The command-line option argument (if used).
  411.  
  412.        This  function  will  be  called  each  time  an option specified in
  413.        scr_opt_list is found on the command line.  It  is  guaranteed  that
  414.        only  options  contained  in  scr_opt_list  will be passed, and each
  415.        option which requires a command-line argument will have one.   Error
  416.        messages  for  poorly  formed  options will be printed by the inter-
  417.        preter and this function will not be called.
  418.  
  419.    scr_setup()
  420.        margin The number of spaces in the right margin.
  421.  
  422.        indent The number of spaces in the left margin.  Note that  normally
  423.               only the output text is indented, not the command prompts.
  424.  
  425.        lines  The  number  of  lines per screenful.  If this value is non-0
  426.               then the TI must make every effort to use this value  as  the
  427.               number of lines per screenful.  If it is 0 then the interface
  428.               must infer the screen size as best it can.
  429.  
  430.        context
  431.               The number of lines that should be kept at  the  top  of  the
  432.               screen  when scrolling; this many lines should be left at the
  433.               top of each page of output if  a  paged  output  mode  is  in
  434.               effect.
  435.  
  436.        This  function is called after the game has initialized and examined
  437.        its command-line arguments but before anything else is done.  It  is
  438.        called  for  both  game-playing  and information modes, so it should
  439.        perform any setup necessary for general stdio printing.
  440.  
  441.        This function should return the number of  characters  that  may  be
  442.        printed  on one line in informational mode.  If game-playing mode is
  443.        to be used then this value is ignored.
  444.  
  445.    scr_shutdown()
  446.        This function should perform any general end processing  appropriate
  447.        for both game-playing and informational modes.
  448.  
  449.    scr_begin()
  450.        This  function  will be called just before the interpreter goes into
  451.        game-playing mode.  If the interpreter  is  running  in  information
  452.        mode this function will never be called.
  453.  
  454.        Any  game-playing mode specific processing should be done here, such
  455.        as opening a new window, clearing the screen, setting terminal char-
  456.        acteristics,  etc.  After this function returns the screen should be
  457.  
  458.  
  459.  
  460. Revision 3.0                    21 October 1992                               7
  461.  
  462.  
  463.  
  464.  
  465.  
  466. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  467.  
  468.  
  469.        set up and the cursor should be positioned at  the  lower-left  hand
  470.        corner of the screen.
  471.  
  472.        Additionally, if the TI supports the creation of a fixed status win-
  473.        dow (in addition to the normal status line) it should call the macro
  474.        F1_SETB(B_STATUS_WIN);  here  to  notify  the game Z-Code so that it
  475.        will properly call the scr_window() and scr_set_win() functions (see
  476.        below).
  477.  
  478.    scr_end()
  479.        This  function  should  perform  any  end processing appropriate for
  480.        game-playing mode only, such as deleting windows, resetting terminal
  481.        characteristics, etc.
  482.  
  483.    scr_putline()
  484.        buffer A  nul-terminated string containing any number of characters.
  485.               The string may be empty, but the pointer will  not  be  NULL.
  486.               There  will  be no newline character ('\n') at the end of the
  487.               string.
  488.  
  489.        This function should print buffer to the screen, performing whatever
  490.        line wrapping, paging, etc. is necessary.  Processing should proceed
  491.        as follows:
  492.  
  493.        For each lineful of characters in buffer:
  494.  
  495.        *   print whatever indent was specified.
  496.  
  497.        *   print a lineful along with a newline and whatever  scrolling  is
  498.            necessary.
  499.  
  500.        *   if  the  interface  supports  paging, and it's enabled, and it's
  501.            been (screenful - context)  lines  since  the  last  prompt  was
  502.            printed, then perform whatever paging is necessary.
  503.  
  504.        If  the  TI  supports  proportional-  and fixed-width fonts then the
  505.        macro call F2_IS_SET(B_FIXED_FONT) should be  used  before  printing
  506.        each line; if the macro returns non-0 then that line must be printed
  507.        in a fixed-width font  if  possible  (maps,  etc.).   If  the  macro
  508.        returns 0 then a proportional font may be used if desired.
  509.  
  510.        If    the    TI    supports    scripting   then   the   macro   call
  511.        F2_IS_SET(B_SCRIPTING) should be checked; if the macro returns non-0
  512.        then buffer should be printed to the script file as well.
  513.  
  514.    scr_putscore()
  515.        This  function  is called whenever the values on the status line are
  516.        to be displayed.  If the interface supports status-line printing and
  517.        it  is  enabled,  then  this  function  should  use  the  values  of
  518.        ti_location and ti_status to display the status line on  the  screen
  519.        in  whatever  manner  it chooses (these variables always contain the
  520.        proper values; they may be used by any TI function).
  521.  
  522.        This function should be also be called whenever the  TI  code  might
  523.  
  524.  
  525.  
  526. Revision 3.0                    21 October 1992                               8
  527.  
  528.  
  529.  
  530.  
  531.  
  532. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  533.  
  534.  
  535.        have disturbed the status line.
  536.  
  537.    scr_putsound()
  538.        number The sound number to be played.
  539.  
  540.        action The action to be taken.
  541.  
  542.        volume The volume at which to play the sound (between 1 and 8).
  543.  
  544.        argc   The number of arguments (1 to 3) passed to the function.
  545.  
  546.        This  function  will  be called by the interpreter if the game being
  547.        played contains sound support.  If  the  interface  doesn't  support
  548.        sound  then  a  simple  output  line may be printed by this function
  549.        stating that fact.
  550.  
  551.        Unfortunately different versions of Infocom games require  different
  552.        methods  of  sound  support, but generally a separate sounds file is
  553.        supplied with the datafile and the  sounds  must  be  retrieved  and
  554.        played from there.
  555.  
  556.    scr_putmesg()
  557.        buffer A  nul-terminated string containing a message from the inter-
  558.               preter.
  559.  
  560.        is_error
  561.               Set to 1 if the message is an error message, or 0 if it's  an
  562.               informational message only.
  563.  
  564.        This  function  is  called whenever the interpreter needs to print a
  565.        message for some reason.  Messages from the game will be printed via
  566.        scr_putline().   The  TI  should  not attempt to exit the program or
  567.        anything else; the interpreter will decide what to do about the mes-
  568.        sage.
  569.  
  570.    scr_getline()
  571.        prompt A  nul-terminated  string  which  is the prompt to be printed
  572.               when requesting a command.
  573.  
  574.        length The maximum number of characters (including the  nul  charac-
  575.               ter) which can be placed in buffer.
  576.  
  577.        buffer A string of length characters, in which the command should be
  578.               returned.
  579.  
  580.        This function is called when the  interpreter  needs  command  input
  581.        from the user.  The function should accept up to length-1 characters
  582.        of input and place them, along with  a  terminating  nul  character,
  583.        into  buffer.   All  command  history, editing, shell escaping, etc.
  584.        etc. must be done internal to this function.  Also if the user types
  585.        more  than length-1 characters the function should flush the rest of
  586.        the input and notify the user that it is doing so.
  587.  
  588.        If this function causes the status line to be  messed  up  (i.e.,  a
  589.  
  590.  
  591.  
  592. Revision 3.0                    21 October 1992                               9
  593.  
  594.  
  595.  
  596.  
  597.  
  598. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  599.  
  600.  
  601.        shell  escape causes extra lines to be printed, etc.) care should be
  602.        taken to rewrite the status line correctly.
  603.  
  604.        The interpreter supports an "interpreter escape mode", where  inter-
  605.        preter  flags  and options may be modified.  This mode is invoked by
  606.        the user typing the escape character (by default ``@'') as the first
  607.        character  on  the  command line.  If this function sees that as the
  608.        first character, it should call ti_escape() with  the  remainder  of
  609.        the  command  line  ( not the escape character).  Once that function
  610.        returns the prompt should be reprinted  and  more  input  should  be
  611.        obtained  without  returning.   If  the TI wishes to provide its own
  612.        escape  commands  it  should  process  them  itself  and  not   call
  613.        ti_escape() for those commands.
  614.  
  615.        The  escape  char by itself will list the available options.  If the
  616.        TI wishes to supply options in addition to the interpreter  options,
  617.        it should call ti_escape() first, then print its own options.
  618.  
  619.        Note  that the TI may provide alternative ways of manipulating these
  620.        options, such as pull-down or pop-up  menus  on  windowing  systems;
  621.        ti_escape() can be called whenever control is properly passed to the
  622.        TI; not from a signal handler, etc.
  623.  
  624.        If the TI supports scripting, then it should check  the  command  to
  625.        see  if  it  was  "script".   If it was and scripting is not already
  626.        enabled then it should be enabled here.  If the enabling fails  then
  627.        an error should be printed and the TI should ask for another command
  628.        without returning to the interpreter.
  629.  
  630.        The function should return the  number  of  characters  placed  into
  631.        buffer, not counting the terminating nul character.
  632.  
  633.    scr_window()
  634.        size   Create  a fixed status window size lines high.  If size is 0,
  635.               then delete the current fixed status window (if any).
  636.  
  637.        This function is called if the game supports a fixed  status  window
  638.        (currently  Seastalker  is  the only such Standard Series game), and
  639.        the TI has registered that it supports such functionality by calling
  640.        F1_SETB(B_STATUS_WIN) in scr_begin() (see above).
  641.  
  642.        The  function will be passed the number of vertical lines needed for
  643.        the fixed status window.  When the window is to be deleted  it  will
  644.        be  passed  an argument of 0.  Note it may be passed a 0 even if the
  645.        window currently doesn't exist; in this  case  the  function  should
  646.        just silently return.
  647.  
  648.        If  the TI doesn't support a fixed status window then just provide a
  649.        dummy function which does nothing.
  650.  
  651.    scr_set_win()
  652.        win    Determines which window to start printing in.
  653.  
  654.        This function is called if the game supports a fixed  status  window
  655.  
  656.  
  657.  
  658. Revision 3.0                    21 October 1992                              10
  659.  
  660.  
  661.  
  662.  
  663.  
  664. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  665.  
  666.  
  667.        (currently  Seastalker  is  the only such Standard Series game), and
  668.        the TI has registered that it supports such functionality by calling
  669.        F1_SETB(B_STATUS_WIN) in scr_begin() (see above).
  670.  
  671.        After  the  scr_window()  function has been called (see above), this
  672.        function will be used to switch back and forth between the two  win-
  673.        dows.   If  called  with  win set to 0, then the TI should set up to
  674.        start printing in the regular text window.  If called with  win  set
  675.        to 1, then set up to start printing in the fixed status window.  All
  676.        actual printing is done with the normal scr_putline() function.
  677.  
  678.    scr_open_sf()
  679.        length The maximum number of characters (including the  nul  charac-
  680.               ter) which can be placed in buffer.
  681.  
  682.        buffer A  string  of length characters, in which the filename should
  683.               be returned.
  684.  
  685.        type   The type of save file to be opened: SF_SAVE,  SF_RESTORE,  or
  686.               SF_SCRIPT.
  687.  
  688.        This  function  is  called when the interpreter needs to open a save
  689.        game file for either saving or restoring, or to open a script  file.
  690.  
  691.        When scr_open_sf() is called, buffer will contain a default filename
  692.        (initially it will be a static name, after the first  call  it  will
  693.        contain  the  last filename entered).  If length is 0, then the file
  694.        should just be opened and the file pointer returned.  If  length  is
  695.        greater  than  0,  the  function should print an appropriate prompt,
  696.        then accept up to length-1 characters of input and place them, along
  697.        with  a  terminating  nul character, into buffer then open that file
  698.        and return the file pointer.
  699.  
  700.        If type is SF_SAVE or SF_SCRIPT, then the file is  being  opened  to
  701.        save the game or write script to and so should be opened for writing
  702.        (binary mode for SF_SAVE and plain text mode  for  SF_SCRIPT).   The
  703.        function  should  test if the file already exists and if so, ask the
  704.        user to confirm overwriting it.
  705.  
  706.        If type is SF_RESTORE, then the file is being opened  to  restore  a
  707.        game and so should be opened for reading in binary mode.
  708.  
  709.        Any  command  history, editing, filename completion, shell escaping,
  710.        etc. etc. must be done internal to this function.  Also if the  user
  711.        types  more  than  length-1 characters the function should flush the
  712.        rest of the input and notify the user that it is doing so.
  713.  
  714.        If this function causes the status line to be  messed  up  (i.e.,  a
  715.        shell  escape causes extra lines to be printed, etc.) care should be
  716.        taken to rewrite the status line correctly.
  717.  
  718.        If the TI wishes to use this function for other purposes,  the  type
  719.        argument  can  be used: the interpreter will only call this function
  720.        with values >=0 for type so the TI is free to call it  with  special
  721.  
  722.  
  723.  
  724. Revision 3.0                    21 October 1992                              11
  725.  
  726.  
  727.  
  728.  
  729.  
  730. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  731.  
  732.  
  733.        values <0 if it wishes.
  734.  
  735.        The  function should return a FILE pointer to the open file.  If the
  736.        user cancels the operation somehow or the open fails, then the func-
  737.        tion  should  return 0 (NULL).  If the return value is NULL then the
  738.        interpreter will examine errno: if errno is 0 then  the  interpreter
  739.        will  assume  the  operation  was  canceled;  if it's non-0 then the
  740.        interpreter will assume there was an error  during  opening  of  the
  741.        file and print an appropriate error message.
  742.  
  743.        If  the  function  returns non-NULL, the interpreter will attempt to
  744.        read/write data from  the  current  position  in  the  file  without
  745.        rewinding  or other manipulation.  This means that you may store TI-
  746.        specific information at the beginning of saved game files  and  read
  747.        them back in when restoring if you like.
  748.  
  749.    scr_close_sf()
  750.        filenm The name of the game file just saved/restored
  751.  
  752.        fp     FILE pointer of the game just saved/restored
  753.  
  754.        type   The  type  of save file to be opened: SF_SAVE, SF_RESTORE, or
  755.               SF_SCRIPT.
  756.  
  757.        This function is called immediately after a game save file is  saved
  758.        or  restored  or  a  script file is to be closed.  At the very least
  759.        this function should perform an fclose(fp) to close the file.  Addi-
  760.        tionally it may add more terminal-specific data, create special con-
  761.        figuration files, change file privileges, etc.
  762.  
  763.        If the TI wishes to use this function for other purposes,  the  type
  764.        argument  can  be used: the interpreter will only call this function
  765.        with values >=0 for type so the TI is free to call it  with  special
  766.        values <0 if it wishes.
  767.  
  768. Writing a New Interface
  769.        If  you  wish  to  create  a  new  TI, I suggest that you start with
  770.        stream.c as the simplest current interface.  Be sure you examine all
  771.        of  this  code  so you understand in detail what each function does.
  772.        You should then create your own .c file and add functionality as you
  773.        like.
  774.  
  775. MAKEFILE
  776.        After  you  create your new TI you should name the .c file something
  777.        relevant, such as pcdos.c for an interface to an  IBM  PC-compatible
  778.        in DOS, or pcwindows.c for an interface to an IBM PC-compatible run-
  779.        ning MS-Windows,  or  something.   Then  you  should  create  a  new
  780.        TERMTYPE  section  in  the Makefile.  Decide what, if any, flags you
  781.        need to give to the compiler and fill in TERMFLAGS; likewise for any
  782.        extra libraries you need and TERMLIB.
  783.  
  784.        If you'd like your interface distributed with the pinfocom distribu-
  785.        tion, and an interface doesn't already exist, then send  it  to  the
  786.        pinfocom  maintainer and he/she'll incorporate it in.  Note you must
  787.  
  788.  
  789.  
  790. Revision 3.0                    21 October 1992                              12
  791.  
  792.  
  793.  
  794.  
  795.  
  796. PINFO_TI(3)                   Contributed Software                  PINFO_TI(3)
  797.  
  798.  
  799.        place your interface code under the GNU Public License for it to  be
  800.        distributed (see the copyright notices in the other files), and pro-
  801.        vide an address for people to contact you about bugs,  enhancements,
  802.        etc. in a comment in the .c file.
  803.  
  804.        If  an  interface  already  exists  then  you'll have to contact the
  805.        author and the two of you can hash it out between you :-).
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856. Revision 3.0                    21 October 1992                              13
  857.  
  858.  
  859.